Q Workflow Optimization Report

Context

This PR addresses issue #4099 where Playwright MCP server was failing to start. The request was to:

1. Pin Playwright to the current released version
2. Add a constant to constants.go
3. Update CLI dependency checker to validate Playwright versions

Changes Made

1. Added Playwright Version Constant (pkg/constants/constants.go)

• Added: DefaultPlaywrightVersion = "1.56.1" constant
• Rationale: Provides a single source of truth for the Playwright version across the codebase
• Benefits: Easier version updates and consistency

2. Updated MCP Configuration Files

Modified files to use the pinned version instead of hardcoded "latest":

pkg/workflow/mcp-config.go

• Before: playwrightPackage := "@playwright/mcp@latest"
• After: playwrightPackage := "@playwright/mcp@" + constants.DefaultPlaywrightVersion
• Uses pinned version (1.56.1) by default
• Still respects custom version configuration when specified

pkg/workflow/mcp_renderer.go

• Before: yaml.WriteString(" \"@playwright/mcp@latest\",\n")
• After: yaml.WriteString(fmt.Sprintf(" \"@playwright/mcp@%s\",\n", constants.DefaultPlaywrightVersion))
• Ensures TOML configuration uses pinned version

3. Added Playwright Version Validation (pkg/workflow/npm_validation.go)

Created new validatePlaywrightVersion() function that:

• Checks Playwright package versions in workflows
• Warns when using "latest" tag instead of pinned version
• Alerts when version doesn't match the pinned constant
• Provides actionable guidance to update to the recommended version

Example output:

⚠ Playwright package '`@playwright/mcp`@latest' uses 'latest' tag. Consider pinning to version 1.56.1 for reproducibility

4. Integrated into Runtime Validation (pkg/workflow/runtime_validation.go)

• Added Playwright version check to Node.js runtime validation flow
• Runs automatically during workflow compilation
• Non-blocking validation (warnings only, not errors)

Expected Improvements

Consistency

• All workflows now use Playwright version 1.56.1 by default
• Eliminates version drift across different workflows
• Ensures reproducible builds

Version Management

• Single constant to update when new Playwright version is released
• CLI validates and warns about version mismatches
• Encourages best practices (pinning versions vs using "latest")

Debugging

• Easier to troubleshoot issues when all workflows use same version
• Clear feedback when workflows deviate from recommended version
• Reduces "works on my machine" scenarios

Validation

All unit tests pass:

• ✅ Existing Playwright tests continue to work
• ✅ No breaking changes to existing workflows
• ✅ New validation function works correctly
• ✅ Version constant properly referenced

Migration Path

For existing workflows using @playwright/mcp@latest:

1. Workflows will continue to function (not a breaking change)
2. Validation will warn about using "latest" tag
3. Users can update to @playwright/mcp@1.56.1 for consistency
4. Or specify custom version via version field if needed

Security Considerations

• Pinning to specific version improves supply chain security
• Reduces risk of automatic updates introducing breaking changes
• Makes dependency auditing more precise

Future Enhancements

Potential follow-ups:

• Add similar validation for other MCP server versions
• Automated Dependabot PRs to update pinned versions
• Version compatibility matrix for different engines

Related Issue: #4099
Testing: Unit tests passing, manual validation completed

AI generated by Q